home *** CD-ROM | disk | FTP | other *** search
/ Risc World 3 / Risc World 3.iso / SOFTWARE / ISSUE3 / PD / VICE / doc / INSTALL < prev    next >
Text File  |  2002-04-08  |  18KB  |  466 lines
  1. Installation notes for VICE
  2. ***************************
  3.  
  4.  
  5. This version of VICE can be compiled and installed under Unix/X-Window,
  6. MS-DOS, MS-Windows, OS2, and this file explains how this can be done.
  7. There is currently no documentation how to compile under RiscOS or BeOS.
  8.  
  9. 1. What you will need
  10. =====================
  11.  
  12.   1.1. Unix
  13.   ---------
  14.  
  15.     To compile VICE under Unix, you basically need a Unix machine
  16.     running the X-Window system version 11 R5 or better, with the
  17.     standard Xt and Xaw libraries.  R4 should work too, but hasn't
  18.     been tested lately.
  19.  
  20.     If you want to use joysticks under Linux, you must install the
  21.     proper joystick module (`joystick-0.8.0.tar.gz' or more recent),
  22.     which is available from `sunsite.unc.edu'.  You can also use a
  23.     customized `joystick-0.8.0.2.tar.gz' that has support for digital
  24.     joysticks connected to the parallel port.  This is available from
  25.     the VICE home page (see the `README' file).
  26.  
  27.     Unlike previous (pre-0.12) versions that only worked with 8-bit
  28.     displays, this release will work with all depths, though 8-bit is
  29.     still highly recommended for best performance.
  30.  
  31.     With version 0.16.0, VICE includes Dag Lem's reSID engine; to
  32.     compile it, you will need a C++ compiler.
  33.  
  34.     NLS (national language support) has been tested with Linux and
  35.     Solaris systems. The following environment variables have to be
  36.     set and exported before starting an emulator:
  37.  
  38.     - Linux: LANGUAGE=de        # de is currently the only available 
  39.                                 # translation
  40.                         
  41.     - Solaris: NLSPATH=${prefix}/lib/locale
  42.                LC_MESSAGES=de
  43.  
  44.     VICE has been compiled successfully on the following Unix systems
  45.     in the past:
  46.  
  47.       - Various i486/Pentium/Pentium Pro PCs running Linux 2.0.x and
  48.         XFree86 3.2/3.3, with both libc 5 and glibc 2;
  49.     Further support for October Gnome and newer Versions should work.
  50.  
  51.       - Some HP9000 (712, 715, 735, 800) machines running HP-UX 9.x
  52.         and 10.x;
  53.  
  54.       - SUN SPARC 5, 10 and Ultra running Solaris 2.3, 2.4, 2.5, 2.5.1
  55.         and 2.7.
  56.     Further support for October Gnome and newer Versions should
  57.         work. Gnome Libraries prior to October Gnome are known to be
  58.         broken with Vice.
  59.         (using gcc);
  60.  
  61.       - SUN SPARC 10 running SunOS 4.1 with both X11R4 and X11R5
  62.         (using gcc);
  63.  
  64.       - SUN SPARC 20 running Linux (2.0.30, RedHat 4.2);
  65.  
  66.       - SGI Indy R5000 and R4600 running Irix 5.3 and 6.2;
  67.  
  68.       - AlphaStation 500/533 with Digital Unix 3.2;
  69.  
  70.       - IBM RS6000 running AIX4.1 (using gcc or IBM C++ Set compiler);
  71.  
  72.       - MkLinux on Apple Macintosh, Kernel 2.0.33, X11R6.3 (no sound).
  73.  
  74.     Unluckily, not all of these systems have been tested with the
  75.     current release.  Success/failure reports are welcome at any time.
  76.     If you encounter any problems, you probably want to read the Hints
  77.     section below.
  78.  
  79.     If you are compiling on a Pentium machine, you might consider
  80.     using the Pentium-specific GCC compiler, which is available at
  81.     `http://www.goof.com/pcg'.  Each time we have tried it, and the
  82.     performance was always at least 20% better (even with just `-O2'
  83.     or `-O3').  However some versions of PGCC are known to produce
  84.     broken executables.  If you observe graphics errors try to compile
  85.     without optimizations.  If the graphics errors disappear, throw
  86.     away your compiler and install another one.
  87.  
  88.     Warning: you might need quite a lot of memory to compile VICE with
  89.     full optimizations on some platforms (in particular, this happens
  90.     with the Pentium-specific GCC).  Moreover, archaic versions of GCC
  91.     (e.g. 2.5.x and older) are known to cause trouble.  In that case,
  92.     it is a good idea to upgrade the compiler to a more recent
  93.     version.
  94.  
  95.   1.2. MS-DOS
  96.   -----------
  97.  
  98.     The MS-DOS port requires the Allegro library by Shawn Hargreaves
  99.     (`http://www.talula.demon.co.uk/allegro') to be compiled.
  100.  
  101.     You might apply this patch to `src/djgpp/timer.c' to achieve better
  102.     results on low end machines.
  103.  
  104.     --- old-timer.c Sat Jan  2 03:29:55 1999
  105.     +++ timer.c     Sat Jan  2 03:30:02 1999
  106.     @@ -197,8 +197,9 @@
  107.            new_delay = bios_counter;
  108.  
  109.         /* fudge factor to prevent interrupts coming too close to each other */
  110.     -   if (new_delay < 1024)
  111.     -      timer_delay = 1024;
  112.     +   /* FIXME: changed from 1024 to 0 (EP) */
  113.     +   if (new_delay < 0)
  114.     +      timer_delay = 0;
  115.         else
  116.            timer_delay = new_delay;
  117.  
  118.     Moreover, you also need DJGPP, the MS-DOS port of GCC
  119.     (`http://www.delorie.com').
  120.  
  121.     Anyway, the current source distribution is only suitable for
  122.     cross-compilation from a Unix system.  This might change in future
  123.     versions.  Help is welcome.
  124.  
  125.   1.3.MS-Windows 
  126.   --------------
  127.  
  128.     There is a separate file `Win32-Howto.txt' in the `doc' directory
  129.     describing what is required to compile VICE under MS-Windows.
  130.  
  131.   1.4. OS/2
  132.   --------------
  133.  
  134.     After unzipping the archive and moving the folder 'Vice2' to
  135.     where-ever-you-want run 'install.cmd' to create the desktop-objects.
  136.  
  137.     Mention that 'install.cmd' does nothing else than creating desktop-
  138.     objects which could be easily removed.
  139.     
  140.  
  141. 2. Configuring and compiling
  142. ============================
  143.  
  144.   2.1. Compiling under Unix, for Unix or MS-DOS
  145.   ---------------------------------------------
  146.  
  147.     The release comes with an auto-configuring script created using
  148.     the GNU autoconf package; this script must be executed before
  149.     compiling VICE to detect the characteristics of your machine and
  150.     specify certain features you might want to enable or disable.
  151.  
  152.     To execute the configuration script, enter the `src' directory of
  153.     the distribution and type:
  154.  
  155.       ./configure <options>
  156.  
  157.     There are several options available, and some of them are not
  158.     necessary for the configuration. The important ones are:
  159.  
  160.       --prefix=PREFIX (default is `/usr/local/')
  161.       --bindir=DIR (default is `PREFIX/bin')
  162.       --mandir=DIR (default is `PREFIX/man')
  163.  
  164.         Specify the place where the VICE executable and support files
  165.         will be installed.
  166.  
  167.       --host=HOST
  168.  
  169.         Specify the host for which the executable will be produced.
  170.         If you want to compile for MS-DOS from a Unix machine using
  171.         GCC, use `--host=i386-go32-gnu'.  If not specified, the
  172.         configure script tries to guess it by itself, so you normally
  173.         don't need to use this option.
  174.  
  175.       --x-includes=DIR
  176.       --x-libraries=DIR
  177.  
  178.         Specify the paths for X11 include files and libraries.  The
  179.         configure script is usually smart enough to find them by
  180.         itself if the setup is not too odd; use these option if it is
  181.         not.
  182.  
  183.       --enable-autobpp
  184.       --enable-8bpp
  185.       --enable-16bpp
  186.       --enable-24bpp
  187.  
  188.         Specify the bit depth of your X11 display.  The default is
  189.         `autobpp', that enables support for all bit depths (the
  190.         emulator tries to find the ones your server supports by itself
  191.         at runtime).  If you think you are going to use only one type
  192.         of display, specifying this might give you (very) slightly
  193.         better performance.
  194.  
  195.       --disable-textfield
  196.  
  197.         Disable Robert W. McMullen's text widget; if you experience
  198.         problems with the text or file manager widgets, you can enable
  199.         the standard Athena one by using this option.  This can also
  200.         be useful if you are using a non-standard Athena-compatible
  201.         library that provides a better looking text widget; it that
  202.         case, using this option will give you that one (this is true
  203.         for neXtaw, for example).
  204.         Problems are known to occur on DEC Alpha systems running
  205.         Digital Unix.
  206.  
  207.       --with-xaw3d
  208.  
  209.         Use Xaw3d (instead of plain Xaw) if present.
  210.  
  211.       --without-resid
  212.       --with-resid=no
  213.  
  214.         Compile without the enhanced reSID engine.
  215.  
  216.       --with-resid=PATH
  217.  
  218.         Compile with a reSID engine located at `PATH'.  This is useful
  219.         in case you want to compile VICE with another version of the
  220.         reSID engine.
  221.  
  222.       --enable-gnomeui
  223.  
  224.         Compile Vice supporting the Gnome libraries. The location of
  225.         the Gnome/Gtk+ libraries are not detected automatically,
  226.         therefore `gnome-config' has to be found in the configuring
  227.         users path. Refer `to src/arch/unix/x11/gnome/TODO' for a list
  228.         of known problems/limitations.
  229.  
  230.      --disable-nls
  231.  
  232.         Force configure to ignore NLS support.
  233.  
  234.  
  235.     (to obtain a complete list of the available options with a
  236.     description, use `./configure --help')
  237.  
  238.     By default, VICE will be compiled by passing the following options
  239.     to the C compiler:
  240.  
  241.       `-g -Wall -O5 -fomit-frame-pointer -funroll-loops
  242.        -finline-functions -fno-strength-reduce'
  243.           on Intel-based x86 Unix systems that have gcc installed;
  244.  
  245.       `-g -Wall -O5 -finline-functions'
  246.           on other systems that have gcc installed;
  247.  
  248.       `-g'
  249.           on systems that do not have gcc installed.
  250.  
  251.     If these options do not fit your needs, you can specify what
  252.     options you want by simply passing them in the `CFLAGS' variable,
  253.     e.g. this is something you might want to do on HP-UX:
  254.  
  255.       CFLAGS="-Ae -g +O3" ./configure
  256.  
  257.     In the same way, you can force usage of a specific C compiler by
  258.     passing the `CC' variable, e.g.:
  259.  
  260.       CC="cc" CFLAGS="-Ae -g +O3" ./configure
  261.  
  262.     To specify a C++ compiler, use the `CXX' variable:
  263.  
  264.       CXX="g++" CFLAGS="-Wall -Wno-strict-prototypes" ./configure
  265.  
  266.     Important notice: if you use the Pentium-specific GCC, some
  267.     optimizations might have to be disabled.  The best way to make
  268.     sure everything works is
  269.  
  270.       CFLAGS="-mpentium -O5 -DNO_REGPARM" ./configure
  271.  
  272.     `-DNO_REGPARM' may also be needed with versions of GCC that have
  273.     buggy implementations of regparms.  Unluckily, we have no way of
  274.     finding about all of them, so you might have to play a bit.
  275.  
  276.     If you are running on a Linux system and the joystick module is
  277.     installed properly, the configure script will auto-detect it and
  278.     support for it will be enabled.  Otherwise, the joystick will be
  279.     only emulated with the numeric keypad.
  280.  
  281.     In case the `configure' script fails or complains about missing
  282.     libraries and you cannot explain this, please send the
  283.     `config.log' file to us together with a precise description of
  284.     your setup; otherwise, we cannot guess what is wrong with it.
  285.  
  286.     When the configure script has finished, the necessary Makefiles
  287.     will be produced and you can simply type
  288.  
  289.       make
  290.  
  291.     to build all the emulators and utilities (`x64', `xvic', `xpet',
  292.     `x128', `xcbm2', `petcat', `c1541') under the `src' directory.  
  293.     It is possible that `configure' is not able to find all the needed
  294.     libraries automatically (this is usually due to a weird setup); if
  295.     this happens, the script will report a warning message but the
  296.     `Makefile' will be produced anyway.  In this case, you can try to
  297.     re-run `configure' with different options or edit the `Makefile's
  298.     by hand to add the missing options.
  299.  
  300.     If you are cross-compiling for MS-DOS, check that all the DJGPP
  301.     libraries and include files, together with Allegro, are in the
  302.     right places.
  303.  
  304.     If you want to install the emulators and utilities, together with
  305.     the documentation and ROM files, just type
  306.  
  307.       make install
  308.  
  309.     The binaries and support files will all go under PREFIX/lib/vice.
  310.     You must of course have write permissions for the directories where
  311.     VICE is to be installed. Normally only the system administrator
  312.     has write access to /usr/local, the default PREFIX. Either ask
  313.     your system administrator to install VICE for you or use a PREFIX
  314.     in your home directory for example, where you do have write access.
  315.  
  316.     If you want to remove VICE from your system, you can use
  317.  
  318.       make uninstall
  319.  
  320.     If you want to re-compile with different options, you should do a
  321.  
  322.       make mrproper
  323.  
  324.     This will also remove the cache of the `configure' script,
  325.     assuring that all the tests are performed from scratch.
  326.  
  327.   2.2. Compiling under MS-DOS, for MS-DOS
  328.   ---------------------------------------
  329.  
  330.     Sorry, no Makefile is currently provided for native MS-DOS
  331.     compilation, mostly because none of us really uses MS-DOS for
  332.     developing.
  333.  
  334.   2.3. Configuring for multiple architectures
  335.   -------------------------------------------
  336.  
  337.     As with most packages using GNU autoconf, you can compile VICE for
  338.     multiple architectures from the same source tree.
  339.  
  340.     To do so, simply create a build directory:
  341.  
  342.       mkdir {build-dir}
  343.  
  344.     Then run `configure' from the VICE source tree:
  345.  
  346.       {vice-source-path}/configure
  347.  
  348.     Of course, you can specify options, flags, etc. as explained on
  349.     par. 2.1.
  350.  
  351.     After you have configured VICE this way, you can simply compile
  352.     VICE as you would normally do, by typing `make'.
  353.  
  354.     For example, you might want to do something like this to produce
  355.     and MS-DOS executable of X64 (let's suppose a cross-compiling GCC
  356.     is installed as `gcc-dos' somewhere in your `$PATH'):
  357.  
  358.       cd sources/vice-0.14.2
  359.       mkdir i386-go32-msdos
  360.       cd i386-go32-msdos
  361.       CC="gcc-dos" CFLAGS="-O5" ../configure --host=i386-go32-msdos
  362.       make x64
  363.  
  364.  
  365. 3. Hints
  366. ========
  367.  
  368.   In this section we compiled some hints about problems we encountered
  369.   on different test machines and different setups. Any comments on or even 
  370.   solutions to these problems are welcome. 
  371.  
  372.   On Unix, if you are using alternative Xaw libraries (e.g. neXtaw,
  373.   Xaw95, Xaw3d) and you are having troubles with the GUI, try to use
  374.   the standard Xaw first.  There are some incompatibilities that can
  375.   cause them to crash or not to work properly.  Xaw3d should work, but
  376.   in any case please try to use the standard Xaw library before
  377.   reporting bugs.
  378.  
  379.   If you can, please use GCC (or EGCS) instead of the vendor's CC
  380.   supplied with your machine: it is usually less buggy and produces
  381.   better code.  On certain systems (most notably SunOS), configure
  382.   might completely refuse to use the standard CC.
  383.  
  384.   Some version of the HP-UX 10.x linker was also reported to fail
  385.   linking `x128'.  Unluckily, we believe it's a bug in the system and
  386.   we don't know a way to fix this problem (and we did not try very
  387.   hard, either).  If you know how, please let us know.
  388.  
  389.   Some versions of GCC seem to have troubles with `-funroll-loops' on
  390.   certain architectures; on an Alpha and a SPARC we have tried to
  391.   compile VICE on, the compiler died while trying to optimize the code
  392.   when this option was specified (GCC version 2.7.2).  If you
  393.   experience such a problem reconfigure by specifying the `CFLAGS' as
  394.   explained above, removing `-funroll-loops'.
  395.  
  396.   SunOS 4.1.x systems running X11R4 can cause a couple of troubles.
  397.   The first one is that `configure' might not find `-lXmu' and `-lXaw'
  398.   properly, because of some issues related to dynamic libraries.  This
  399.   would need some custom `configure' checks, which might be made
  400.   available in future versions.  For now, just edit `src/Makefile'
  401.   after it has been created by `configure' and add `-lXaw -lXmu' (in
  402.   this order) before `-lXt' on the `LIBS=...' line.  Moreover, you
  403.   might get undefined references to
  404.  
  405.     _get_wmShellWidgetClass
  406.     _get_applicationShellWidgetClass
  407.  
  408.   when linking `x64', `xvic' or `xpet'.  In that case you have to link
  409.   `-lXmu' statically (default is dynamically).  This can be done by
  410.   editing the `Makefile' by hand and replacing `-lXmu' with `-Bstatic
  411.   -lXmu -Bdynamic' in the `LIBS=...'  line.  A simplier way is to link
  412.   *everything* statically; this can be achieved by running `configure'
  413.   like this:
  414.  
  415.     LDFLAGS="-static" ./configure
  416.  
  417.   This will build much bigger executables, though.  We are sorry, but
  418.   that is not our fault.
  419.  
  420.   Some HP-UX (versions 9 and 10) need the "--without-readline" switch
  421.   because autoconf fails to detect that it needs "-lcurses"
  422.   (the configure test passes, but the compile is broken. Is this an
  423.   autoconf bug?). 
  424.  
  425.   One HP-UX 9 test machine failed to compile resid.cc, probably 
  426.   due to a broken gcc installation. In this case try to apply this 
  427.   patch:
  428. --------------------------
  429. --- vice-old/src/sid/resid.cc  Wed Mar 10 22:57:19 1999
  430. +++ vice-new/src/sid/resid.cc  Mon Apr 12 16:22:03 1999
  431. @@ -27,10 +27,11 @@
  432.  
  433.  #include "resid/sid.h"
  434.  
  435. -extern "C" {
  436.  
  437.  #include <stdio.h>
  438.  #include <math.h>
  439. +
  440. +extern "C" {
  441.  
  442.  #include "vice.h"
  443.  #include "sid.h"
  444. --------------------------
  445.   
  446.   When compiling on AIX in a directory different from where the source 
  447.   is and with the native C++ compiler "cc", then the C++ compiler mixes 
  448.   up the order in which include files are included. This makes the `resid'
  449.   package wrongly believe that `bool' is defined. You might use
  450.   `CXX="cc -qidirfirst"' instead. 
  451.   On the other hand using "cc" as C++ compiler resulted in a linkage 
  452.   error on our test machine. We thus recommend using the GCC C++ compiler 
  453.   or the configure switch `--without-resid'.
  454.   If you know how to fix this, any comments are welcome.
  455.  
  456.   On a DEC alpha-EV6 machine (64 bit, OSF1 operating system) when using
  457.   the DEC compiler, you might want to use `CC="cc -std1"' to enforce ANSI C
  458.   standard.
  459.  
  460.   To build a debug version of VICE, use `CFLAGS="-g -DNO_INLINE"'.
  461.   This disables inlining of functions in most of the places and does not
  462.   do any optimization. This way the debugger can produce a much better 
  463.   output. This also serves as a test whether the compiler optimization
  464.   breaks the code.
  465.  
  466.